Using API Documentation to Define Solution

Overview

As we all know the number of enterprise customer or consumer use multiple products or applications to complete their desired task or job. For companies to thrive in the complex and competitive world and provide seamless customer experience, speed to market is key to success. Companies integrate with third-party APIs to expand into newer product segments while providing better customer experience.
API stands for Application Programming Interface and it enables products or applications to talk to each other. API is the code that determines whether a product or application can access the server, and what information is it allowed to access or modify. Companies expose APIs with supporting documentation for other companies (i.e partners) to integrate. Partners utilize these APIs to launch new features or enhance existing features faster to the market instead of taking multiple quarters or sometimes years to develop it from scratch. Any newly developed functionality that is available via the API can be leveraged with minimal effort by the partners.
Some popular third-party APIs that are widely used:

** Stripe API: **

• Process payments by charging a credit card or debit card
• Charge customers on a recurring basis
• Offer discounts to customers for a specific period of time

** Whatsapp API: **

• Companies can provide real-time notifications and include documents or images into their message
• Customer can interact with a company or vice-versa
• Encourage customers to provide feedback instantly at the end of service

Although the partners can save multiple quarters or years of development and maintenance effort, integration with third-party APIs has its disadvantages as well.
It is important to not have the entire product dependent or rely on third-party APIs completely. It adds significant risk and dependency on these companies with third-party APIs. These third-party integrations are usually available at a cost and some APIs charge on a transaction basis or limit the number of transactions. For e.g Stripe offers a standard fee for handling credit card transactions and a discount for large volume transactions. This cost cannot be ignored and needs to be considered as part of the development and maintenance cost by you as Product Manager
Understanding the basics of an API will allow you as a Product Manager to engage with internal stakeholders, engineering teams, and customers when third-party API integration is being explored or used to provide new functionality and enhance the user experience.

We will focus on understanding the key details that you need to know about an API as a Product Manager. In the case of Technical Product Manager, it definitely goes beyond the information shared here.

• ** REST: ** REST stands for representational state transfer. A REST API needs to adhere to a set of architectural principles and characteristics. The REST API architecture describes six constraints and these can be learned from the Become Technical Enough Further Research section -characteristics of A REST API. At a very high-level, a REST API is resource-based. A resource refers to a thing and nouns are used here. For e.g Plan, Subscription, etc. Representation of the resources (which is a thing) in various ways. When an API call is made from the client to the server, the response contains a representation of the resource. JSON is the commonly used format and XML is also used
• ** Authentication: ** Not all products or applications can access an API. You need to have pre-approved access (just like how you need access code to enter some buildings). In the case of APIs, this access code is called the authentication token. A company like Stripe or Whatsapp will issue the token and credentials for you to access their API. As part of this, the company will also determine what information and actions are you allowed to carry out (for e.g after entering the building using the access code you can access five floors and use all the tools available). The former is authentication which confirms your identity, while authorization will determine what you are allowed to access and carry out as actions or view information. Username, password and authentication token is required for authentication. OAuth framework is adopted by companies to authenticate and authorize partners
• ** Requests and responses: ** This is communication that happens between the client and the servers. As per the API documentation, a partner can request for information in a specific format and if the partner is authorized to access this information, the server responds with something in return in JSON or XML formation. The API documentation contains information around the different types of requests that are allowed and what can you expect to receive in the response
• ** Headers: ** Both the request and response will include headers, which contains useful information. The header typically includes authorization details, content type i.e how is the information provided to the partner and what content is included, and date indicates the request or response's date and time
• ** HTTP Methods: ** Partners request for information using HTTP methods ( think of these as commands or instructions with a clear definition of what needs to be done. There are many methods, but the most common methods used are: create, read, update and delete information (referred to as CRUD). Some commonly used methods are
  • POST: Used to create a new resource. For e.g company can create a new message using Whatsapp API for a specific customer
  • GET: Read the information you requested from the representation of a resource. For e.g. Retrieve the invoice for a specific customer using Stripe API
  • PUT: Update data. For e.g Update the billing address for a specific customer using Stripe API
  • DELETE: Delete data. For e.g. Delete a customer using Stripe API
• ** Endpoints: ** It accepts the request from the client to access the API resources. Remember a company can have many endpoints but they need to be exposed for the partners to access. Let's breakdown a Stripe API's endpoint: DELETE v1/customers/: id
  • HTTPS method is DELETE
  • Endpoint is * v1/customers/: id * used to delete a specific customer
  • * Returns * an object with the deleted parameter on success, and an error message if the customer ID doesn't exist
• ** API calls: ** The request made to API is referred to as API calls. When you connect the different details we discussed above, an API call is used to hit an exposed endpoint and if you are authorized to access the API and the requested API, you will receive the information you need. In the case of Stripe API, you made an API call to the Delete endpoint with a specific customer ID and Stripe will respond with a success message or an error depending upon whether the customer ID is found or not
• ** Payload: ** Another terminology used to refer to the response from the API is Payload. The payload refers to the important information you receive in the response that you need to pay attention to since the response contains a lot of information. For e.g, the payload from Stripe API to retrieve a specific customer's data will include address, currency, email, and name.
• ** Response Codes: ** The API response also includes a response code. This code is a numerical value with a specific meaning associated with it. These response codes are meaningful especially to the Product Manager to be able to determine the different scenarios when an API call fails and determine if these failures need to be exposed to the end-user in a more meaningful and actionable format. E.g. if the Stripe API call to process payment using a credit card failed due to payment method declined, then the Product Manager can decide to display an error message to inform the user about the same. Common response codes include:
  • 200: Success. All good!
  • 301: The resource being requested is moved permanently
  • 400: Ran into a client problem. Another common error you may have seen on the website (Oops! 404 Error)
  • 500: Ran into a server problem
• ** Rate limiting: ** Companies may impose an overall limit on the number of APIs calls a partner can make. This is called Application rate limit/ throttle limit etc. This means in some cases if the partner exceeds the maximum number of requests allowed, then the processing may slow down or in some cases return an error indicating the limit has been exceeded. Some companies have a tier-based pricing model to accommodate partners with differing needs:
  All the information discussed above and more is captured by companies using API documentation. This documentation will help you and especially the engineering team understand the different functionalities.